Create an Entity

Overview

This document describes the procedure to create an entity in any work system using the SyncNow DevOps Gate. We provide Groovy scripts for Jenkins, or you can copy and paste cURL commands from our user interface in the DevOps Gate project configuration.

Overview

Usage Examples

Creating a bug when automated testing fails.
Creating a bug when a security vulnerability is found.
Creating a service ticket when an incident is identified in another system.

Creating an Entity

This procedure creates an entity according to the mapping definition. SyncNow will update an existing entity if it has the same title/summary or matches a defined filter.

Create An Entity

Request

The request URL should include the system ID, which can be copied from the DevOps Process definition page.

POST /api/v1.0/DevOpsGate/Enrich/{DevOpsProjectID}?action=create

The payload contains the parameters as defined in the DevOps Gate Process and their values. Below are the parameters defined for the example request.

Parameter	Description
Param1…ParamX	Parameters as defined in the DevOps Gate per entityType mapping
`subProject`	The target work system project as defined in the DevOps Gate Process. Work systems for publishing can be limited through SyncNow DevOps Process configuration
`entityType`	The entity to be created
`CreateIfEntityDoesNotExistByTitleOtherwiseUpdate`	Whether to create an entity if found a similar one with the same title

[
  {
    "fields": [
      {
        "key": "Param1",
        "value": "string"
      },
      {
        "key": "Param2",
        "value": "string"
      },
      {
        "key": "Param3",
        "value": "string"
      }
    ],
    "subProject": "MyProject",
    "entityType": "Bug",
    "CreateIfEntityDoesNotExistByTitleOtherwiseUpdate": "false"
  }
]

Response

Syntax	Description
SystemID	The system where the entities were created
EntitiesID	The IDs of the entities created
Error	Errors that occurred during the creation process
Warning	Warnings that occurred during the creation process

 {
    "updatedEntitiesID": [
        {
            "systemID": "10",
            "entityKeys": [
                "CLS-3938"
            ]
        }
    ],
    "errors": [],
    "warnings": []
}

Jenkins Groovy Script

Below is a Groovy code example that creates an entity with SyncNow DevOps Gate.

@NonCPS
def getCommentsString() {
    def list = []
    def changeLogSets = currentBuild.changeSets
    for (int i = 0; i < changeLogSets.size(); i++) {
        def entries = changeLogSets[i].items
        for (int j = 0; j < entries.length; j++) {
            def entry = entries[j]
            if (entry.msg != null) {
               list.add("""${entry.commitId} on ${new Date(entry.timestamp)}: ${entry.msg.replaceAll("[\n\r]", " ")}""")
            }
        }
    }
    return list.join(',')
}

pipeline {
    agent any

    stages {
        stage('Clone') {
            steps {
                echo 'Clone Code'
            }
        }
        stage('Version') {
            steps {
                echo 'Version'
            }
        }
        stage('Test') {
            steps {
                echo 'Test'
            }
        }
        stage('Build') {
            steps {
                echo 'Build'
            }
        }
        stage('Publish') {
            steps {
                echo 'Publish'
            }
        }
        stage('Notify SyncNow') {
            steps {
                echo 'Notify'
                echo "Job Name is ${JOB_NAME}, Build ID is ${env.BUILD_ID}"
                script {
                    def commits = getCommentsString()
                    def payload = """
[
 {
  "fields": [
   {
    "key": "Param1",
    "value": "string"
   },
   {
    "key": "Param2",
    "value": "string"
   },
   {
    "key": "Param3",
    "value": "string"
   }
  ],
  "subProject": "MyProject",
  "entityType": "Bug"  
 }
]
                    """
                    // Create entities and update entities from commit. Result in format for adding attachments
                    def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON', httpMode: 'POST', authentication: 'SyncNow', requestBody: "${payload}", url: "https://<SyncNowBaseURL>/api/v1.0/app/DevOpsGate/Enrich/<DevOpsProjectID>?action=create"

                    println("Status: ${response.status}")
                    println("Content: ${response.content}")
                }
            }
        }
    }
}

Step-by-Step Instructions

Example: Create If… and Update an Entity Action

Create a DevOps Gate Process.
Navigate to the Mapping Entities page.
Navigate to the Mapping Options page for specific entity mappings.

Navigate To Mapping Page

Add filters. In the example below, a filter by Status is added.

Duplicate Detection: Entity names are always checked by their summary/title. If an entity with the same name/title and type is found, it will be updated.

Filter Entities For Update